Summary

Expose the perceptual-hash (pHash) of dataset items through the SDK so ML workflows (dedup, near-duplicate detection) can access it without a separate fetch.

• Adds a new phash: Optional[str] field to the DatasetItem dataclass — 64-character "0/1" binary string when backfilled by the backend, None otherwise.
• Threads phash=payload.get(PHASH_KEY) into DatasetItem.from_json. Because every SDK method that returns a DatasetItem goes through from_json, this single change exposes item.phash on:
  • items_and_annotation_generator
  • items_generator / dataset.items
  • query_items
  • iloc / refloc / loc
• Bumps version 0.18.2 → 0.18.3 and adds a CHANGELOG entry per the project's Keep-a-Changelog convention.
• Adds a top-level CLAUDE.md capturing release workflow, branch/PR conventions, and the from_json-centralization insight for future agent sessions.

Test plan

• Local install: poetry install && poetry run python -c "from nucleus.dataset_item import DatasetItem; print(DatasetItem.from_json({'reference_id':'r', 'image_url':'x.jpg', 'phash':'1'*64}).phash)" prints the hash.
• DatasetItem.from_json falls back to None when the backend omits phash (existing test fixtures).
• Smoke test against fedramp-prod once the paired backend PR is deployed: client.get_dataset(...).items_and_annotation_generator(...) yields items with item.phash populated.
• CHANGELOG renders correctly on the release tag.

🤖 Generated with Claude Code

Greptile Summary

This PR exposes the backend-computed perceptual hash (phash) on DatasetItem by adding a new Optional[str] field and threading it through the single from_json deserialization entry point, making it available across all SDK methods that return items.

• Adds PHASH_KEY = "phash" constant and phash: Optional[str] = None field to the DatasetItem dataclass; phash is intentionally omitted from to_payload since it is read-only and computed by the Nucleus backend.
• Bumps the version to 0.18.3 and prepends a matching CHANGELOG entry following the project's Keep-a-Changelog convention.
• Adds CLAUDE.md to document the repo's release workflow and architecture for future AI-assisted sessions.

Important Files Changed

sequenceDiagram
    participant C as Caller (user code)
    participant SDK as SDK method<br/>(items_generator / query_items / iloc / etc.)
    participant FJ as DatasetItem.from_json
    participant API as Nucleus REST API

    C->>SDK: call SDK method
    SDK->>API: GET /v1/nucleus/...
    API-->>SDK: JSON payload (includes "phash" when backfilled)
    SDK->>FJ: from_json(payload)
    FJ->>FJ: payload.get(PHASH_KEY)  →  phash or None
    FJ-->>SDK: "DatasetItem(phash="0101...", ...)"
    SDK-->>C: DatasetItem with .phash populated

_{Reviews (2): Last reviewed commit: "Tighten phash field comment" | Re-trigger Greptile}